<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <title>CGILua: Building Web Scripts with Lua</title>
    <link rel="stylesheet" href="doc.css" type="text/css"/>
	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
</head>
<body>

<div id="container">
	
<div id="product">
	<div id="product_logo"><a href="http://www.keplerproject.org">
		<img alt="CGILua logo" src="cgi-128.gif"/>
	</a></div>
	<div id="product_name"><big><strong>CGILua</strong></big></div>
	<div id="product_description">Building Web Scripts with Lua</div>
</div> <!-- id="product" -->

<div id="main">
	
<div id="navigation">
<h1>CGILua</h1>
	<ul>
		<li><a href="index.html">Home</a>
			<ul>
				<li><a href="index.html#overview">Overview</a></li>
				<li><a href="index.html#status">Status</a></li>
				<li><a href="index.html#download">Download</a></li>
				<li><a href="index.html#history">History</a></li>
				<li><a href="index.html#incompatibility">Incompatibilities</a></li>
				<li><a href="index.html#credits">Credits</a></li>
				<li><a href="index.html#contact">Contact us</a></li>
			</ul>
		</li>
		<li><a href="manual.html">Manual</a>
			<ul>
				<li><a href="manual.html#intro">Introduction</a></li>
				<li><a href="manual.html#installation">Installation</a></li>
				<li><a href="manual.html#config">Configuration</a></li>
				<li><a href="manual.html#scripts">Lua Scripts</a></li>
				<li><a href="manual.html#templates">Lua Pages</a></li>
				<li><a href="manual.html#parameters">Parameters</a></li>
				<li><a href="manual.html#dispatching">Dispatching</a></li>
                <li><a href="manual.html#authentication">Authentication</a></li>
               <li><a href="manual.html#error_handling">Error Handling</a></li>
			</ul>
		</li>
		<li><strong>Reference</strong>
			<ul>
				<li><a href="reference.html#headers">Headers</a></li>
				<li><a href="reference.html#contents">Content Generation</a></li>
				<li><a href="reference.html#prep">Lua Pages</a></li>
				<li><a href="reference.html#variables">CGILua Variables</a></li>
				<li><a href="reference.html#error_handling">Error Handling</a></li>
				<li><a href="reference.html#behavior">CGILua Behavior</a></li>
				<li><a href="reference.html#urlcode">URL Encoding</a></li>
				<li><a href="reference.html#auxiliar">Auxiliary functions</a></li>
				<li><a href="reference.html#index">Alphabetic Index</a></li>

			</ul>
		</li>
		<li><a href="libraries.html">Libraries</a>
			<ul>
				<li><a href="libraries.html#authentication">Authentication</a></li>
				<li><a href="libraries.html#cookies">Cookies</a></li>
				<li><a href="libraries.html#dispatcher">Dispatcher</a></li>
				<li><a href="libraries.html#serialize">Serialize</a></li>
				<li><a href="libraries.html#session">Session</a></li>
			</ul>
		</li>
		<li><a href="sapi.html">SAPI</a></li>
		<li><a href="license.html">License</a></li>
	</ul>
</div> <!-- id="navigation" -->

<div id="content">


<h2><a name="headers"></a>Headers</h2>

<p>Headers functions are used to change the HTTP response headers and consist of:</p>

<dl class="reference">
    <dt><a name="contentheader"></a><strong><code>cgilua.contentheader (type, subtype)</code></strong></dt>
    <dd>Sends a <em>Content-type</em> header with the given values of type and
    sub-type.<br/>
    Both arguments are strings: <code>type</code> is the header type;
    <code>subtype</code> is the header sub-type.<br/>
    Returns nothing.</dd>
    
    <dt><a name="header"></a><strong><code>cgilua.header (header, value)</code></strong></dt>
    <dd>Sends a generic header. This function should <em>not</em> be used to
    generate a <em>Content-type</em> nor a <em>Location</em> header because
    some launchers/web-servers use different functions for this purpose.<br/>
    Both arguments are strings: <code>header</code> is the name of the header;
    <code>value</code> is its value.<br/>
    Returns nothing.</dd>

    <dt><a name="htmlheader"></a><strong><code>cgilua.htmlheader ()</code></strong></dt>
    <dd>Sends the header of an HTML file (<em>Content-type: text/html</em>).<br/>
    Returns nothing.</dd>
    
    <dt><a name="redirect"></a><strong><code>cgilua.redirect (url, args)</code></strong></dt>
    <dd>Sends the header to force a redirection to the given URL adding the
    parameters in table <code>args</code> to the new URL.<br/>
    The first argument (<code>url</code>) is the URL the browser should be
    redirected to; the second one (<code>args</code>) is an optional table
    which could have pairs <em>name = value</em> that will be encoded to form
    a valid URL (see function <a href="#encodetable">cgilua.urlcode.encodetable</a>).<br/>
    Returns nothing.</dd>
</dl>


<h2><a name="contents"></a>Content Generation</h2>

<p>Content generation functions are used to output text to the response and to
generate URLs in the CGILua format. They consist of:</p>

<dl class="reference">
    <dt><a name="mkabsoluteurl"></a><strong><code>cgilua.mkabsoluteurl (path)</code></strong></dt>
    <dd>Creates an absolute URL containing the given URL <code>path</code>.<br/>
    Returns the resulting absolute URL.</dd>
    
    <dt><a name="mkurlpath"></a><strong><code>cgilua.mkurlpath (script [, args])</code></strong></dt>
    <dd>Creates an URL path to be used as a link to a CGILua <code>script</code>
    using the optional table of arguments (<code>args</code>). The arguments are
    used in the URL as query string parameters.<br/>
    Returns the resulting URL.</dd>

    <dt><a name="print"></a><strong><code>cgilua.print (...)</code></strong></dt>
    <dd>Sends the given arguments to the client. This function converts all its
    arguments to strings before sending them to the server thus it does not
    raises errors like <a href="put">cgilua.put</a>.<br/>
    Returns nothing.</dd>

    <dt><a name="put"></a><strong><code>cgilua.put (...)</code></strong></dt>
    <dd>Sends the given arguments to the client. This function should
    always be used; do not use Lua's <code>print</code> or <code>io.write</code>
    for output otherwise your script may not work for every launching method.<br/>
    Returns nothing.</dd>
</dl>

<h2><a name="prep"></a>Lua Pages</h2>

<p>Lua Pages functions are used to process Lua Pages templates and to define the
behavior of this processing. They consist of:</p>

<dl class="reference">
    <dt><a name="handlelp"></a><strong><code>cgilua.handlelp (filename[, env])</code></strong></dt>
    <dd>Equivalent to <a href="include"><code>cgilua.lp.include</code></a> but
    sends the HTML header before the pre-processed file.<br/>
    Returns nothing.</dd>
    
    <dt><a name="compile"></a><strong><code>cgilua.lp.compile (string)</code></strong></dt>
    <dd>Compile a piece of code given as a string into a Lua function.
    The string is translated with
    <a href="#translate"><code>cgilua.lp.translate</code></a>
    into another string which is transformed into a function with
    <code>loadstring</code>.
    The resulting function is cached internaly and reused if the same piece of
    code is given.<br/>
    Returns a function.</dd>

    <dt><a name="include"></a><strong><code>cgilua.lp.include (filename[, env])</code></strong></dt>
    <dd>Pre-processes a Lua Page template (given by <code>filename</code>) and sends the results
    to the client. The file content is processed by <a href="#compile"><code>cgilua.lp.compile</code></a>
    and no headers are sent. If an optional environment table is passed, the file is executed with this
    environment instead of the global one. This can be used to sandbox your scripts.<br/>
    Returns nothing.</dd>
    
    <dt><a name="setcompatmode"></a><strong><code>cgilua.lp.setcompatmode (boolean)</code></strong></dt>
    <dd>Turns on or off the compatibility mode. Turning it on will make the
    Lua Pages preprocessor understand the <em>expression fields</em> and
    <em>code fields</em> structures used by previous versions of CGILua.<br/>
    Default value: <code>true</code><br/>
    Returns nothing.</dd>
    
    <dt><a name="setoutfunc"></a><strong><code>cgilua.lp.setoutfunc (funcname)</code></strong></dt>
    <dd>Defines the name of the output function for templates. The Lua Pages
    preprocessor will generate calls to the function with the given
    <code>funcname</code> (a string).<br/>
    Returns nothing.</dd>
    
    <dt><a name="translate"></a><strong><code>cgilua.lp.translate (string)</code></strong></dt>
    <dd>Uses the Lua Pages preprocessor to generate a string corresponding to
    the Lua code that executes the Lua chunks and/or expressions inside the
    given <code>string</code>.<br/>
    Returns a string with the resulting Lua code.</dd>
</dl>


<h2><a name="variables"></a>CGILua Variables</h2>

<p>CGILua Variables offers information about the script being processed and
the <a href="sapi.html#servervariable">CGI environment variables</a> depending
on the Web server and launcher used.
They consist of both atributes and functions:</p>

<dl class="reference">
    <dt><a name="script_file"></a><strong><code>cgilua.script_file</code></strong></dt>
    <dd>The file name of the running script. Obtained from
    <a href="#script_path"><code>cgilua.script_path</code></a>.</dd>
    
    <dt><a name="script_path"></a><strong><code>cgilua.script_path</code></strong></dt>
    <dd>The complete path of the running script. This variable is usually the
    same as the <a href="sapi.html#servervariable">CGI environment variable</a>
    <code>PATH_TRANSLATED</code>.</dd>
    
    <dt><a name="script_pdir"></a><strong><code>cgilua.script_pdir</code></strong></dt>
    <dd>The directory of the running script. Obtained from
    <a href="#script_path"><code>cgilua.script_path</code></a>.</dd>
    
    <dt><a name="script_vdir"></a><strong><code>cgilua.script_vdir</code></strong></dt>
    <dd>The virtual directory of the running script. Obtained from
    <a href="#script_vpath"><code>cgilua.script_vpath</code></a>.</dd>
    
    <dt><a name="script_vpath"></a><strong><code>cgilua.script_vpath</code></strong></dt>
    <dd>The complete virtual path of the running script. Equivalent to the
    <a href="sapi.html#servervariable">CGI environment variable</a>
    <code>PATH_INFO</code>.</dd>
    
    <dt><a name="servervariable"></a><strong><code>cgilua.servervariable (varname)</code></strong></dt>
    <dd>Returns a string with the value of the CGI environment variable
    correspoding to <code>varname</code>. For a list of CGI variables please refer to
    <a href="sapi.html#servervariable">SAPI.Request.servervariable</a></dd>

    <dt><a name="tmp_path"></a><strong><code>cgilua.tmp_path</code></strong></dt>
    <dd>The directory used by <a href="#tmpfile"><code>cgilua.tmpfile</code></a>.
    Obtained by checking <code>os.getenv("TEMP")</code>, <code>os.getenv ("TMP")</code> and
    <code>"/tmp"</code> in that order.</dd>
    
    <dt><a name="urlpath"></a><strong><code>cgilua.urlpath</code></strong></dt>
    <dd>The name of the script. Equivalent to the
    <a href="sapi.html#servervariable">CGI environment variable</a>
    <code>SCRIPT_NAME</code>.</dd>
</dl>

<h2><a name="error_handling"></a>Error Handling</h2>

<p>CGILua error handling functions allow the redefinition of how errors are
handled and presented to the user. The consist of:</p>

<dl class="reference">
    <dt><a name="errorlog"></a><strong><code>cgilua.errorlog (string)</code></strong></dt>
    <dd>Sends the given <code>string</code> to the error log file.<br/>
    Returns nothing.</dd>
    
    <dt><a name="seterrorhandler"></a><strong><code>cgilua.seterrorhandler (func)</code></strong></dt>
    <dd>Sets the <em>error handler</em> function to <code>func</code>.
    This function is called by Lua when an error occurs. It receives the error
    message generated by Lua and it is responsible for generating and returning
    the correct error message to be used by CGILua.<br/>
    Returns nothing.</dd>
    
    <dt><a name="seterroroutput"></a><strong><code>cgilua.seterroroutput (func)</code></strong></dt>
    <dd>Sets the <em>error output</em> function to <code>func</code>.
    This function is called by Lua to generate the error output itself.<br/>
    Returns nothing.</dd>
</dl>

<h2><a name="behavior"></a>CGILua behavior</h2>

<p>The behavior of CGILua can be configured using this set of functions:</p>

<dl class="reference">
    <dt><a name="addclosefunction"></a><strong><code>cgilua.addclosefunction (func)</code></strong></dt>
    <dd>Defines a function (<code>func</code>) to be called after the execution
    of the script requested.<br/>
    Returns nothing.</dd>
    
    <dt><a name="addopenfunction"></a><strong><code>cgilua.addopenfunction (func)</code></strong></dt>
    <dd>Defines a function (<code>func</code>) to be called before the execution
    of the script requested.<br/>
    Returns nothing.</dd>

    <dt><a name="addscripthandler"></a><strong><code>cgilua.addscripthandler (ext, func)</code></strong></dt>
    <dd>Defines a function (<code>func</code>) to pre-process files with a
    certain extension (<code>ext</code>). The default configuration uses
    <a href="#doscript"><code>cgilua.doscript</code></a> to process Lua Scripts
    (<code>.lua</code> files) and <a href="#handlelp"><code>cgilua.handlelp</code></a>
    to process Lua Pages (<code>.lp</code> files).<br/>
    Returns nothing.</dd>

    <dt><a name="buildplainhandler"></a><strong><code>cgilua.buildplainhandler (type, subtype)</code></strong></dt>
    <dd>Creates a <em>script handler</em> that sends the given header and the plain
    file requested. The <em>Content-type</em> header is formed by the two arguments;
    the created function will receive a <em>filename</em> as its only argument
    and will return the given filename untouched.<br/>
    Returns a function.</dd>
    
    <dt><a name="buildprocesshandler"></a><strong><code>cgilua.buildprocesshandler (type, subtype)</code></strong></dt>
    <dd>Creates a <em>script handler</em> that sends the given header and the
    processed file requested. The <em>Content-type</em> header is formed by the
    two arguments; the created function will receive a <em>filename</em> as its
    only argument and will return the given filename pre-processed by the
    function <a href="#include">cgilua.lp.include</a>.<br/>
    Returns a function.</dd>
    
    <dt><a name="setmaxfilesize"></a><strong><code>cgilua.setmaxfilesize (size)</code></strong></dt>
    <dd>Sets the maximum <code>size</code> (in bytes) for each uploaded file.
    This value is bounded by the <em>maximum total input size</em> (see
    <a href="#setmaxinput">cgilua.setmaxinput</a>). This function only takes
    effect if used before POST data is processed, therefore its use in scripts
    are meaningless.<br/>
    Returns nothing.</dd>
    
    <dt><a name="setmaxinput"></a><strong><code>cgilua.setmaxinput (size)</code></strong></dt>
    <dd>Sets the <em>maximum total input</em> <code>size</code> allowed (in bytes).
    This function only takes efect if used before POST data is processed,
    therefore its use in scripts are meaningless.<br/>
    Returns nothing.</dd>
</dl>

<h2><a name="urlcode"></a>URL encoding functions</h2>

<p>CGILua enconding functions allow the processing of URL strings in a simple way:</p>

<dl class="reference">
    <dt><a name="encodetable"></a><strong><code>cgilua.urlcode.encodetable (table)</code></strong></dt>
    <dd><em>URL-encode</em> the elements of a <code>table</code> creating a
    string to be used as a URL for passing data/parameters to another script.<br/>
    Returns a string representing the encoded argument table.</dd>
    
    <dt><a name="escape"></a><strong><code>cgilua.urlcode.escape (string)</code></strong></dt>
    <dd><em>URL-encode</em> a <code>string</code>.<br/>
    Returns the encoded string.</dd>
    
    <dt><a name="insertfield"></a><strong><code>cgilua.urlcode.insertfield (args, name, value)</code></strong></dt>
    <dd>Adds the given <code>value</code> to the field indexed by <code>name</code>
    in the <code>args</code> table. If the field already has a value, it is
    transformed into a table with this value at index <code>1</code> and
    the new value at index <code>2</code>. Other values will be added at
    the end of the <em>array-part</em> of the created table.<br/>
    Returns nothing.</dd>
    
    <dt><a name="parsequery"></a><strong><code>cgilua.urlcode.parsequery (query, args)</code></strong></dt>
    <dd>Parse URL-encoded request data. This could be the <code>query</code>
    part of the script URL or URL-encoded POST data. Each decoded
    <em>name = value</em> pair is inserted into the <code>args</code> table.<br/>
    Returns nothing.</dd>
    
    <dt><a name="unescape"></a><strong><code>cgilua.urlcode.unescape (string)</code></strong></dt>
    <dd><em>URL-decodes</em> a <code>string</code>.<br/>
    Returns the decoded string.</dd>
</dl>

<h2><a name="auxiliar"></a>Auxiliar functions</h2>

<dl class="reference">
    <dt><a name="doif"></a><strong><code>cgilua.doif (filepath)</code></strong></dt>
    <dd>Executes a file (given by <code>filepath</code>) if it exists. 
    Returns the values returned by the execution, or
    <tt>nil</tt> followed by an error message if the file does not exists.</dd>

    <dt><a name="doscript"></a><strong><code>cgilua.doscript (filepath)</code></strong></dt>
    <dd>Executes a file (given by <code>filepath</code>). Raises an error if it
    occurs. In case of success, returns the values returned by the execution.</dd>

    <dt><a name="pack"></a><strong><code>cgilua.pack (...)</code></strong></dt>
    <dd>Returns a new table with all the passed arguments stored in it.</dd>

    <dt><a name="splitonfirst"></a><strong><code>cgilua.splitfirst (path)</code></strong></dt>
    <dd>Returns two strings with the "first directory" and the "remaining paht" of the given
    <code>path</code> string splitted on the first separator ("/" or "\").</dd>
    
    <dt><a name="splitonlast"></a><strong><code>cgilua.splitonlast (path)</code></strong></dt>
    <dd>Returns two strings with the "directory path" and "file" parts of the given
    <code>path</code> string splitted on the last separator ("/" or "\").
    This function used to be called <code>cgilua.splitpath</code> and still can be accessed by
    this name for compatibility reasons. <code>cgilua.splitpath</code> may be deprecated in future
    versions.</dd>
    
    <dt><a name="tmpfile"></a><strong><code>cgilua.tmpfile (dir[, namefunction])</code></strong></dt>
    <dd>Returns a temporary file in the <code><a href="#tmp_path">cgilua.tmp_path</a></code> directory
    using an optional name generator. If the name generator function is not passed,
    <code>cgilua.tmpname</code> is used. The file is removed by CGILua after the request has been
    processed.</dd>

    <dt><a name="tmpname"></a><strong><code>cgilua.tmpname ()</code></strong></dt>
    <dd>Returns a temporary name using an adjusted version of <code>os.tmpname</code>.</dd>
</dl>

<h2><a name="index"></a>Alphabetic Index</h2>

<a href="#addclosefunction">addclosefunction</a><br/>
<a href="#addopenfunction">addopenfunction</a><br/>
<a href="#addscripthandler">addscripthandler</a><br/>
<a href="#buildplainhandler">buildplainhandler</a><br/>
<a href="#buildprocesshandler">buildprocesshandler</a><br/>
<a href="#contentheader">contentheader</a><br/>
<a href="#doif">doif</a><br/>
<a href="#doscript">doscript</a><br/>
<a href="#encodetable">encodetable (urlcode)</a><br/>
<a href="#errorlog">errorlog</a><br/>
<a href="#escape">escape (urlcode)</a><br/>
<a href="#header">header</a><br/>
<a href="#htmlheader">htmlheader</a><br/>
<a href="#include">include (lp)</a><br/>
<a href="#insertfield">insertfield (urlcode)</a><br/>
<a href="#mkabsoluteurl">mkabsoluteurl</a><br/>
<a href="#mkurlpath">mkurlpath</a><br/>
<a href="#pack">pack</a><br/>
<a href="#parsequery">parsequery (urlcode)</a><br/>
<a href="#handlelp">handlelp</a><br/>
<a href="#lp">lp</a><br/>
<a href="#print">print</a><br/>
<a href="#put">put</a><br/>
<a href="#redirect">redirect</a><br/>
<a href="#script_file">script_file</a><br/>
<a href="#script_path">script_path</a><br/>
<a href="#script_pdir">script_pdir</a><br/>
<a href="#script_vdir">script_vdir</a><br/>
<a href="#script_vpath">script_vpath</a><br/>
<a href="#servervariable">servervariable</a><br/>
<a href="#setcompatmode">setcompatmode (lp)</a><br/>
<a href="#seterrorhandler">seterrorhandler</a><br/>
<a href="#seterroroutput">seterroroutput</a><br/>
<a href="#setlibdir">setlibdir</a><br/>
<a href="#setmaxfilesize">setmaxfilesize</a><br/>
<a href="#setmaxinput">setmaxinput</a><br/>
<a href="#setoutfunc">setoutfunc (lp)</a><br/>
<a href="#splitonfirst">splitonfirst</a><br/>
<a href="#splitonlast">splitonlast</a><br/>
<a href="#tmpfile">tmpfile</a><br/>
<a href="#tmpname">tmpname</a><br/>
<a href="#tmp_path">tmp_path</a><br/>
<a href="#urlcode">urlcode</a><br/>
<a href="#unescape">unescape (urlcode)</a><br/>
<a href="#urlpath">urlpath</a><br/>

</div> <!-- id="content" -->

</div> <!-- id="main" -->

<div id="about">
	<p><a href="http://validator.w3.org/check?uri=referer">Valid XHTML 1.0!</a></p>
	<p><small>$Id: reference.html,v 1.46 2007/12/05 19:41:13 carregal Exp $</small></p>
</div> <!-- id="about" -->

</div> <!-- id="container" -->

</body>
</html> 
